Inside Macintosh: QuickDraw GX Objects /

Chapter 6 - Transform Objects / Using Transform Objects

Manipulating Transform Object Properties

This section describes how to manipulate the common object properties of transform objects: owner count and tag list. It also describes how to restore a transform object's properties to their default values.

To manipulate the clip of an transform, see the section "Getting, Setting, and Modifying the Transform Clip" beginning on page 6-20. To manipulate the mapping of a transform, see the section "Moving, Scaling, Rotating, and Skewing Shapes" beginning on page 6-23. To manipulate the view port list of a transform, see the section "Manipulating the View Port List" beginning on page 6-28. To manipulate the hit-test parameters of a transform, see the section "Setting Up Hit-Test Parameters" beginning on page 6-30.

For manipulating a transform object as a whole, see "Creating and Manipulating Transform Objects" beginning on page 6-15.

Manipulating a Transform Object's Owner Count

The owner count of an object indicates the number of current references to that object. In general, QuickDraw GX manages owner counts for you. For example, when you create a new transform object, QuickDraw GX sets the owner count of the new transform to 1. When you assign an existing transform object to a shape, QuickDraw GX increments the transform's owner count, corresponding to the new reference to the transform contained in the shape object.

For example, in Listing 6-1 on page 6-16, the call to GXNewTransform to create the transform myTransform sets its owner count to 1; the subsequent call to GXSetShapeTransform increments the owner count of myTransform, so it is 2. The call to GXDisposeTransform decrements the owner count of myTransform, making
it 1 again. The transform is not deleted, which is appropriate because it is still used by the shape. If you were to call GXSetShapeTransform again to associate a different transform object with the shape, or call GXDisposeShape when the shape is no longer needed, the owner count of myTransform would decrement again, this time to 0, and it would be deleted.

As another example, the code in Listing 6-2 on page 6-17 clones a transform object before removing its reference from a shape. The cloning increments the transform's owner count, to ensure that the transform is not deleted when its owner count is decremented by the call to GXSetShapeTransform that removes it from the shape.

If you want to manage a transform's owner count directly, or if you want to know whether a transform object is shared, you can use the GXGetTransformOwners function to determine the owner count of a transform, and the GXCloneTransform
and GXDisposeTransform functions to change the owner count of a transform. The GXCloneTransform function increments the transform's owner count, and the GXDisposeTransform function decrements the transform's owner count, freeing the memory used by the transform if the owner count goes to 0.

In the chapter "Style Objects" in this book, the section on manipulating a style object's owner count discusses two common owner-count problems and how to avoid them. The problems are discussed in terms of style objects, but they apply equally well to transform objects. Refer to that discussion if you find that transform objects you create have owner counts that are higher or lower than you expect.

The GXGetTransformOwners function is described on page 6-39.

Getting and Setting a Transform Object's Tag References

You can examine the list of references to tag objects currently associated with a transform object using the GXGetTransformTags function. Once you create a tag object, you can attach it to a transform object using the GXSetTransformTags function. You can attach as many tag objects as you like to a transform object.

Tag objects and the basic functions for manipulating them are described in the chapter "Tag Objects" in this book. That chapter also lists the common tag types defined and reserved by Apple Computer, Inc.

The GXGetTransformTags function is described on page 6-40. The GXSetTransformTags function is described on page 6-41.

Resetting Default Transform Properties

If you explicitly create a new transform with the GXNewTransform function and then modify its properties, or if you indirectly modify the properties of a shared transform (by calling, for example, GXSetShapeMapping) and thereby cause QuickDraw GX to create a new transform, that new transform has nondefault properties. If you want to restore the default transform properties, you can call the GXResetTransform function. This function resets the transform's clip, mapping, view port list, and hit-test parameters to their default values, but does not alter its owner count or tag list.

The GXResetTransform function is described on page 6-38.